---
title: Referencia de directivas de maquetado
i18nReady: true
---

import Since from '~/components/Since.astro';
import ReadMore from '~/components/ReadMore.astro'

**Las directivas de maquetado** son atributos especiales de HTML disponibles dentro del maquetado de los componentes de Astro (archivos `.astro`), algunas de ellas también pueden usarse en archivos `.mdx`.

Las directivas de maquetado se utilizan para controlar el comportamiento de un elemento o componente de cierta forma. Una directiva de maquetado puede habilitar alguna característica del compilador que te haga la vida más fácil (como usar `class:list` en lugar de `class`). O bien, una directiva puede decirle al compilador de Astro que haga algo especial con ese componente (como hidratar con `client:load`).

Esta página describe todas las directivas de maquetado disponibles en Astro y cómo funcionan.

## Reglas

Para que una directiva de maquetado sea válida, debes:

- Incluir dos puntos `:` en su nombre, usando la forma `X:Y` (ej.: `client:load`).
- Ser visible para el compilador (ej.: `<X {...attr}>` no funcionaría si `attr` contuviera una directiva).

Algunas directivas de plantilla, no todas, pueden tomar un valor personalizado:
- `<X client:load />` (no toma valor)
- `<X class:list={['some-css-class']} />` (toma una matriz)

Una directiva de maquetado nunca se incluye directamente en el HTML del compilado final de un componente.

## Directivas comunes

### `class:list`

`class:list={...}` toma un array de clases y los convierte en un string. Esto está impulsado por la popular biblioteca auxiliar de [@lukeed](https://github.com/lukeed/clsx) llamada [clsx](https://github.com/lukeed/clsx).

`class:list` toma un array de varios tipos de valores posibles diferentes:
- `string`: Agregado al elemento `class`
- `Object`: Todas las keys verdaderas se agregan al elemento `class`
- `Array`: aplanado
- `false`, `null`, o `undefined`: Omitido

```astro
<!-- Esto -->
<span class:list={[ 'hello goodbye', { world: true }, [ 'friend' ] ]} />
<!-- Se convierte en -->
<span class="hello goodbye world friend"></span>
```

### `set:html`

`set:html={string}` inyecta un string de HTML en un elemento, similar a la opción `el.innerHTML`.

**¡Astro no verifica automáticamente el valor!** Asegúrate que confías en el valor o verificalo manualmente antes de pasarlo al maquetado. Olvidar hacer esto te expondrá a ataques de [Cross Site Scripting (XSS)](https://owasp.org/www-community/attacks/xss/).

```astro
---
const rawHTMLString = "Hola <strong>Mundo</strong>"
---
<h1>{rawHTMLString}</h1>
  <!-- Resultado: <h1>Hola &lt;strong&gt;Mundo&lt;/strong&gt;</h1> -->
<h1 set:html={rawHTMLString} />
  <!-- Resultado: <h1>Hola <strong>Mundo</strong></h1> -->
```

También puedes usar `set:html` en un `<Fragment>` para evitar agregar un elemento contenedor innecesario. Esto puede ser especialmente útil al obtener HTML de un CMS.

```astro
---
const cmsContent = await fetchHTMLFromMyCMS();
---
<Fragment set:html={cmsContent}>
```

`set:html={Promise<string>}` inyecta una cadena HTML en un elemento que está envuelto en una Promise.

Puede utilizarse para inyectar HTML almacenado externamente, como en una base de datos.

```astro
---
import api from '../db/api.js';
---
<article set:html={api.getArticle(Astro.props.id)}></article>
```

`set:html={Promise<Response>}` inyecta una [Respuesta](https://developer.mozilla.org/en-US/docs/Web/API/Response) en un elemento.

Esto es más útil cuando se usa `fetch()`. Por ejemplo, recuperar publicaciones antiguas de un anterior generador de sitios estáticos.

```astro
<article set:html={fetch('http://example/old-posts/making-soup.html')}></article>
```

`set:html` se puede utilizar en cualquier etiqueta y no es necesario incluir HTML. Por ejemplo, puede utilizarse con [`JSON.stringify()`](https://developer.mozilla.org/es/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) en una etiqueta `<script>` para agregar un esquema [JSON-LD](https://json-ld.org/) a su página.

```astro
<script type="application/ld+json" set:html={JSON.stringify({
  "@context": "https://schema.org/",
  "@type": "Person",
  name: "Houston",
  hasOccupation: {
    "@type": "Occupation",
    name: "Astronaut"
  }
})}/>
```


### `set:text`

`set:text={string}` inyecta un string de texto en un elemento, similar a `el.innerText`. A diferencia de `set:html`, Astro verifica automáticamente al valor `string` que se pasa.

Esto equivale a pasar una variable a una expresión de maquetado de forma directa (por ejemplo: `<div>{someText}</div>`) y, por lo tanto, esta directiva no se usa comúnmente.

## Directivas del cliente

Estas directivas controlan cómo se hidratan los [componentes de framework](/es/guides/framework-components/) en la página.

De forma predeterminada, un componente de framework no está hidratado en el cliente. Si no se proporciona la directiva `client:*`, su HTML se representa en la página sin JavaScript.

Una directiva de cliente puede ser usada solamente en un componente de framework UI que sea directamente importado en un componente `.astro`. Las directivas de hidratación no son compatibles cuando se usan [etiquetas dinámicas](/es/basics/astro-syntax/#etiquetas-dinámicas) y [componentes personalizados pasados a través de la propiedad `components`](/es/guides/markdown-content/#componentes-personalizados-con-mdx-importado).

### `client:load`

- **Prioridad:** Alta
- **Útil para:** Elementos de la UI inmediatamente visibles que deben ser interactivos lo antes posible.

Carga e hidrata el JavaScript del componente inmediatamente al cargar la página.

```astro
<BuyButton client:load />
```

### `client:idle`

- **Prioridad:** Media
- **Útil para:** Elementos de UI de menor prioridad que no necesitan ser interactivos inmediatamente.

Carga e hidrata el componente JavaScript una vez que la página haya terminado con su carga inicial y se haya activado el evento `requestIdleCallback`. Si está en un navegador que no es compatible con [`requestIdleCallback`](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback), entonces se usará el evento [`load`](https://developer.mozilla.org/es/docs/Web/API/Window/load_event).

```astro
<ShowHideButton client:idle />
```

### `client:visible`

- **Prioridad:** Baja
- **Útil para:** Elementos de la interfaz de usuario de baja prioridad que se encuentran en la parte inferior de la página ("que no son visibles al usuario") o que requieren tantos recursos para cargar que preferiría no cargarlos en absoluto si el usuario nunca vio el elemento.

Carga e hidrata el JavaScript del componente una vez que haya ingresado al viewport del usuario. Esto utiliza un `IntersectionObserver` internamente para realizar un seguimiento de la visibilidad.

```astro
<HeavyImageCarousel client:visible />
```

#### `client:visible={{rootMargin}}`
<p><Since v="4.1.0" /></p>

Opcionalmente, se puede pasar un valor para `rootMargin` al `IntersectionObserver` subyacente. Cuando se especifica `rootMargin`, el componente de JavaScript se hidratará cuando un margen especificado (en píxeles) alrededor del componente entre en el viewport, en lugar del propio componente.

```astro
<HeavyImageCarousel client:visible={{rootMargin: "200px"}} />
```

Especificar un valor de `rootMargin` puede reducir los desplazamientos de diseño (CLS), permitir más tiempo para que un componente se hidrate en conexiones a internet más lentas y hacer que los componentes sean interactivos antes, mejorando la estabilidad y la capacidad de respuesta de la página.

### `client:media`

- **Prioridad:** Baja
- **Útil para:** Alternar las barras de navegación u otros elementos que solo deben mostrarse en ciertos tamaños de pantalla.

`client:media={string}` carga e hidrata el componente JavaScript una vez que se cumple una determinada media query de CSS.

:::note
Si el componente ya está oculto y se muestra mediante media queries de CSS, entonces puede ser más fácil simplemente usar `client:visible` y no pasar la misma media query a la directiva.
:::

```astro
<SidebarToggle client:media="(max-width: 50em)" />
```

### `client:only`

`client:only={string}` **evita** la renderización del servidor HTML y solo se renderiza en el cliente. Actúa de manera similar a `client:load` en el sentido de que carga, procesa e hidrata el componente inmediatamente al cargar la página.

**¡Debes pasar el framework correcto al componente!** Debido a que Astro no ejecuta el componente durante su compilación/en el servidor, Astro no sabe qué framework usa el componente a menos que se lo indiques explícitamente.

```astro
<SomeReactComponent client:only="react" />
<SomePreactComponent client:only="preact" />
<SomeSvelteComponent client:only="svelte" />
<SomeVueComponent client:only="vue" />
<SomeSolidComponent client:only="solid-js" />
<SomeLitComponent client:only="lit" />
```

### Directivas de cliente personalizadas

Desde Astro 2.6.0, las integraciones también pueden agregar directivas `client:*` personalizadas para cambiar cómo y cuándo se deben hidratar los componentes.

Consulta la [API `addClientDirective`](/es/reference/integrations-reference/#opción-addclientdirective) para saber más sobre cómo crear una directiva de cliente personalizada.


## Directivas Script & Style

Estas directivas solo se pueden usar en etiquetas HTML `<script>` y `<style>`, para controlar cómo se manejan el JavaScript y CSS del lado del cliente en la página.

### `is:global`

De forma predeterminada, Astro aplica automáticamente las reglas CSS `<style>` localmente al componente. Puedes optar por no participar con este comportamiento con la directiva `is:global`.

`is:global` hace que el contenido de una etiqueta `<style>` se aplique globalmente en la página cuando el componente es incluido. Esto deshabilita el alcance local de CSS de Astro. Esto es equivalente a envolver todos los selectores dentro de una etiqueta `<style>` con `:global()`.

Puedes combinar `<style>` y `<style is:global>` juntos en el mismo componente para crear algunas reglas de estilo globales mientras mantienes la mayor parte del CSS con un alcance local dentro del componente de Astro.

<ReadMore>Consulta la página [Estilos & CSS](/es/guides/styling/#estilos-globales) para obtener más detalles sobre cómo funcionan los estilos globales.</ReadMore>

```astro
<style is:global>
  body a { color: red; }
</style>
```

### `is:inline`

De forma predeterminada, Astro procesará, optimizará y empaquetará cualquier etiqueta `<script>` y `<style>` que vea en la página. Puedes optar por evitar este comportamiento con la directiva `is:inline`.

`is:inline` le indica a Astro que deje la etiqueta `<script>` o `<style>` tal como está en el HTML final. Los contenidos no serán procesados, optimizados o agrupados. Esto limita algunas características de Astro, como importar un paquete npm o usar un lenguaje de compilación a CSS como Sass.

La directiva `is:inline` significa que las etiquetas `<style>` y `<script>`:

- No se empaquetarán como un archivo externo. Esto significa que [atributos tales como `defer`](https://es.javascript.info/script-async-defer) que controlan la carga de archivos externos, no tendrán efecto.
- No se deduplicarán: el elemento aparecerá tantas veces como se represente.
- No se resolverán sus referencias `import`/`@import`/`url()` en relación con el archivo `.astro`.
- Se renderizarán en el HTML final exactamente donde se crearon.
- Los estilos serán globales y no tendrán alcance local en el componente.

:::caution
La directiva `is:inline` está implícita cada vez que se usa cualquier atributo que no sea `src` en una etiqueta `<script>` o `<style>`.
:::

```astro
<style is:inline>
  /* inline: Las importaciones de paquetes relativos y npm no son compatibles. */
  @import '/assets/some-public-styles.css';
  span { color: green; }
</style>

<script is:inline>
  /* inline: Las importaciones de paquetes relativos y npm no son compatibles. */
  console.log('Estoy inline aquí en el HTML generado.');
</script>
```

<ReadMore>Mira cómo funcionan los [scripts del lado del cliente](/es/guides/client-side-scripts/) en los componentes de Astro.</ReadMore>

### `define:vars`

`define:vars={...}` pueden pasar variables del servidor desde el frontmatter del componente a las etiquetas `<script>` o `<style>` del cliente. Cualquier variable de frontmatter *JSON-serializable* es compatible, incluyendo las `props` pasadas al componente a través de `Astro.props`. Los valores son serializados por medio de [`JSON.stringify()`](https://developer.mozilla.org/es/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify)

```astro
---
const foregroundColor = "rgb(221 243 228)";
const backgroundColor = "rgb(24 121 78)";
const message = "¡Astro es espectacular!";
---
<style define:vars={{ textColor: foregroundColor, backgroundColor }}>
  h1 {
    background-color: var(--backgroundColor);
    color: var(--textColor);
  }
</style>

<script define:vars={{ message }}>
  alert(message);
</script>
```

:::caution
El uso de `define:vars` en una etiqueta `<script>` o `<style>` implica la directiva [`is:inline`](#isinline), lo que significa que los scripts o estilos no se empaquetarán y serán incluidos inline directamente en el HTML.

Esto se debe a que cuando Astro empaqueta los scripts, Astro incluye y ejecuta los scripts una sola vez, aun si incluyes el componente que contiene el script múltiples veces en una página. `define:vars` requiere que un script se re-ejecute con los valores asignados, luego Astro crea, en su lugar, un script inline.

Para scripts, intenta [pasar variables a los scripts manualmente](/es/guides/client-side-scripts/#pasando-variables-frontmatter-a-scripts) en su lugar.
:::

## Directivas avanzadas

### `is:raw`

`is:raw` indica al compilador de Astro que trate a cualquier elemento hijo de ese componente como texto. Esto significa que toda la sintaxis especial de maquetado de Astro se ignorará dentro de este componente.

Usado internamente por el componente `<Markdown />`.

Por ejemplo, si tuvieras un componente Katex personalizado que convierte texto a HTML, podrías hacer que los usuarios hicieran esto:

```astro
---
import Katex from '../components/Katex.astro';
---
<Katex is:raw>Algunas {sintaxis} conflictivas aquí</Katex>
```
